Error Handling

Understanding and handling SuperDoc API errors gracefully

Error Response Format

All SuperDoc API errors follow a consistent JSON structure:

{
  "code": "ERROR_CODE",
  "error": "Error Type",
  "message": "Human-readable error description",
  "requestId": "req_abc123",
  "timestamp": "2024-01-15T10:30:00Z"
}

code · string · required

Machine-readable error code for programmatic handling

error · string · required

HTTP status text (e.g., “Bad Request”, “Unauthorized”)

message · string · required

Human-readable error description

requestId · string · required

Unique identifier for the request (useful for support)

timestamp · string

ISO 8601 timestamp when the error occurred

HTTP Status Codes

SuperDoc API uses standard HTTP status codes:

400 Bad Request

Client Error - Invalid request format or parameters

Common causes:

• Missing required parameters
• Invalid file format
• Malformed request body
• File too large

401 Unauthorized

Authentication Error - Invalid or missing API key Common causes: - Missing Authorization header - Invalid API key format - Expired or revoked API key

403 Forbidden

Authorization Error - Valid credentials but insufficient permissions Common causes: - Plan limitations exceeded - Feature not available in current plan - IP address restrictions

429 Too Many Requests

Rate Limiting - Request quota exceeded Common causes: - Hourly rate limit exceeded - Daily rate limit exceeded - Burst limit exceeded

500 Internal Server Error

Server Error - Unexpected server-side issue Common causes: - Temporary service disruption - Document processing failure - Resource exhaustion

503 Service Unavailable

Service Unavailable - Temporary service interruption

Common causes:

• Scheduled maintenance
• System overload
• Dependency failures

Common Error Codes

Authentication Errors

MISSING_AUTH

{
  "code": "MISSING_AUTH",
  "error": "Unauthorized",
  "message": "Authorization header is required",
  "requestId": "req_abc123"
}

File Processing Errors

INVALID_FILE_TYPE

{
  "code": "INVALID_FILE_TYPE",
  "error": "Bad Request",
  "message": "Only DOCX files are supported for conversion",
  "requestId": "req_jkl012"
}

Rate Limiting Errors

RATE_LIMIT_EXCEEDED

{
  "code": "RATE_LIMIT_EXCEEDED",
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 3600 seconds",
  "requestId": "req_vwx234",
  "retryAfter": 3600
}

Error Handling Strategies

Basic Error Handling

JavaScript

async function convertDocument(file) {
  try {
    const response = await fetch('/v1/convert?format=pdf', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
      },
      body: formData
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.code} - ${error.message}`);
    }

    return await response.blob();

} catch (error) {
console.error('Conversion failed:', error.message);
throw error;
}
}

Advanced Error Handling with Retry Logic

Exponential Backoff

class SuperDocClient {
  constructor(apiKey, maxRetries = 3) {
    this.apiKey = apiKey;
    this.maxRetries = maxRetries;
  }

async convertWithRetry(file) {
for (let attempt = 0; attempt < this.maxRetries; attempt++) {
try {
return await this.convert(file);
} catch (error) {
if (this.shouldRetry(error, attempt)) {
const delay = this.calculateDelay(attempt);
await this.sleep(delay);
continue;
}
throw error;
}
}
}

shouldRetry(error, attempt) {
if (attempt >= this.maxRetries - 1) return false;

    // Retry on server errors and rate limits
    return error.status >= 500 || error.status === 429;

}

calculateDelay(attempt) {
// Exponential backoff with jitter
const baseDelay = Math.pow(2, attempt) _ 1000;
const jitter = Math.random() _ 1000;
return baseDelay + jitter;
}

sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}

Error Handling Best Practices

Use specific error handling

Handle different error types with appropriate responses:

function handleApiError(error) {
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      return scheduleRetry(error.retryAfter);
    case 'FILE_TOO_LARGE':
      return showFileSizeError();
    case 'INVALID_FILE_TYPE':
      return showFileTypeError();
    case 'INVALID_API_KEY':
      return redirectToAuth();
    default:
      return showGenericError();
  }
}

Log errors for debugging

Always log errors with context:

function logError(error, context) {
  console.error('SuperDoc API Error:', {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    timestamp: error.timestamp,
    context: context
  });
}

Provide user-friendly messages

Translate technical errors into user-friendly messages:

const ERROR_MESSAGES = {
  'INVALID_FILE_TYPE': 'Please select a valid Word document (.docx file)',
  'FILE_TOO_LARGE': 'File size must be less than 25MB',
  'RATE_LIMIT_EXCEEDED': 'Too many requests. Please try again later',
  'CONVERSION_FAILED': 'Unable to convert document. Please try again'
};

Implement graceful degradation

Provide alternatives when the API is unavailable:

async function convertWithFallback(file) {
  try {
    return await superDocConvert(file);
  } catch (error) {
    if (error.status >= 500) {
      // Fallback to alternative service or queue for later
      return fallbackConverter(file);
    }
    throw error;
  }
}

Monitoring and Alerting

Error Rate Monitoring

Track error rates to identify issues:

class ErrorTracker {
  constructor() {
    this.errors = new Map();
    this.window = 60000; // 1 minute
  }

  recordError(errorCode) {
    const now = Date.now();
    const windowStart = now - this.window;

    if (!this.errors.has(errorCode)) {
      this.errors.set(errorCode, []);
    }

    const timestamps = this.errors.get(errorCode);
    timestamps.push(now);

    // Remove old timestamps
    this.errors.set(
      errorCode,
      timestamps.filter((t) => t > windowStart)
    );
  }

  getErrorRate(errorCode) {
    const timestamps = this.errors.get(errorCode) || [];
    return timestamps.length;
  }
}

Health Check Implementation

async function healthCheck() {
  try {
    const response = await fetch("https://api.superdoc.dev/v1/health");
    return response.ok;
  } catch (error) {
    return false;
  }
}

// Monitor API health
setInterval(async () => {
  const isHealthy = await healthCheck();
  if (!isHealthy) {
    console.warn("SuperDoc API appears to be down");
    // Trigger alerts or fallback behavior
  }
}, 30000); // Check every 30 seconds

Getting Help

When encountering persistent errors:

Check Status Page

Monitor service status and planned maintenance

Contact Support

Include the requestId for faster troubleshooting

Always include the requestId from error responses when contacting support. This helps us quickly locate and diagnose the specific request.